home *** CD-ROM | disk | FTP | other *** search
/ Pascal Super Library / Pascal Super Library (CW International)(1997).bin / PGM_TOOL / PARAMS / CONFIG.DOC < prev    next >
Text File  |  1992-02-26  |  9KB  |  213 lines
  1.                     CONFIG Program Documentation
  2.  
  3. The program CONFIG is a general-purpose configuration program that
  4. can change the configuration (default options) of a named target file
  5. (an .exe program) to specified options.  The target program must use
  6. a compatible method.  Two sections follow, describing first the use
  7. of the CONFIG program, and second, how to write a program that will
  8. be reconfigurable by CONFIG.
  9.  
  10. ----------------------------------------------------------------------
  11.  
  12.                     Using the CONFIG Program
  13.  
  14. A summary of the usage of the CONFIG program is displayed if the
  15. CONFIG program is run with less than two command-line parameters:
  16.  
  17.         CONFIG  (c) 2-12-92 J. M. Clark
  18.         Reconfigures a target program with given options.
  19.         Usage:   config TargetPath Options [ +s ]
  20.         Example: config c:\bin\target /c+/b-/a12/xname
  21.         The parameters may be in any order.
  22.         TargetPath is the program filename minus the final '.exe'.
  23.         Options is one parameter beginning with '/'.
  24.         Use '+s' to retain the backup (.ex$) file.
  25.         Messages report reconfiguration success or failure.
  26.         Run the target program with option '/?'
  27.         to check that the options are appropriate.
  28.  
  29. In the above example, the default options of the program file
  30. c:\bin\target.exe are changed to /c+ /b- /a12 and /xname.  Note
  31. that the '.exe' extension must not be included on the CONFIG
  32. command line, and that no spaces may appear between the options.
  33.  
  34. Note also that the CONFIG program has no way of determining if
  35. the given options are appropriate for the target program.  It
  36. is suggested to run the target program with option '/?' to check
  37. the options; the next section discusses this further.
  38.  
  39. The CONFIG program replaces ALL of the default options of the target
  40. program with the given options.  (That is, all options that are
  41. reconfigurable by the CONFIG method.)  The result of omitting options
  42. in the CONFIG command line is discussed in the section "Making a
  43. Program Reconfigurable".
  44.  
  45. The +s option causes the original target file to be saved with a ".ex$"
  46. extension.  Normally, the backup ".ex$" file is used temporarily while
  47. converting the target file, then automatically deleted.
  48.  
  49. The following messages may be displayed by CONFIG.  Futher explanations
  50. are given here.  The given target pathname is represented by +FName+
  51. in this list.
  52.  
  53. Cannot find target file "+FName+.exe".
  54.  
  55.     If a name like "target.exe.exe" is reported, the name "target.exe"
  56.     was given on the command line, and the CONFIG program added another
  57.     ".exe"; do not include the ".exe" on the CONFIG command line.
  58.     Otherwise, check that a correct directory path prefixes the program
  59.     filename.
  60.  
  61. Could not locate target data.
  62.  
  63.     Typically, this indicates that the target program does not use
  64.     the CONFIG method for reconfiguration.  (See next section.)
  65.  
  66. Source data is too long for target.
  67.  
  68.     The CONFIG program detects the length of the configuration data
  69.     space in the target program file, and measures the length of
  70.     the source data (the options parameter string from the command
  71.     line).  This message indicates that the target program does not
  72.     have sufficient space for the given options.
  73.  
  74. Could not change target.
  75.  
  76.     This can happen only if the target program is faulty.
  77.  
  78. Could not finish rewriting target.
  79.  
  80.     This can happen if there is insufficient disk space for the old
  81.     (backup) and new copies of the target file.
  82.  
  83. Reconfiguration completed.
  84.  
  85.     So far, so good.  But run the target program with the /? option
  86.     so that it can check that the new options are understood.
  87.  
  88. Original target is now named +FName+.ex$
  89. New (bad?) target is now named +FName+.exe
  90. Try: fc /b +FName+.ex$ +FName+.exe
  91.  
  92.     This message appears when the target file is found, any error
  93.     is detected, and the +s option WAS specified.  However, for most
  94.     errors, the new file is an unchanged copy of the original.  It
  95.     is suggested that the FC (File Compare) program may be used to
  96.     determine if the old and new files differ.  For the "could not
  97.     finish rewriting" error, the new file is probably smaller than
  98.     the original file.
  99.  
  100. Original target file is unchanged.
  101.  
  102.     This message appears when the target file is found, any error
  103.     is detected, and the +s option was NOT specified.  In this case,
  104.     the new file is deleted and the backup file is renamed as the
  105.     original.
  106.  
  107. ----------------------------------------------------------------------
  108.  
  109.                 Making a Program Reconfigurable
  110.  
  111. The following Turbo Pascal program illustrates a method of initializing
  112. the default options of a program so that they can be reconfigured by
  113. the CONFIG program.  It can be used to test the CONFIG program.
  114.  
  115. For further details of the method, see the Skel.pas program, discussed
  116. later.
  117.  
  118.         program target; {test}
  119.  
  120.         type
  121.             tConfig = record
  122.                 magic: string[10];
  123.                 cdata: string[20];
  124.             end;
  125.  
  126.         const
  127.             Config: tConfig = (
  128.                 magic: '!)@(#*$&%^';
  129.                 cdata: '/c+/d-/e12//////////'
  130.             );
  131.  
  132.         begin
  133.             writeln(Config.cdata);
  134.         end.
  135.  
  136. Other programming languages can also be used, but the tConfig record
  137. structure must remain the same.  If using another language, check that
  138. the compiler generates strings prefixed by a length byte, and that the
  139. "cdata" string immediately follows the "magic" string in the .exe file.
  140.  
  141. The CONFIG program searches the target .exe file for the "magic" string,
  142. which gives the location of the "cdata" string.  The length byte that
  143. preceeds the cdata string indicates how much data space is available.
  144. The '/////////' padding after the actual data is used to reserve space
  145. for configuration changes.  For this reason, '//' is defined as a
  146. special "option" that terminates the actual data.
  147.  
  148. In the target program, four stages of option definition can be
  149. supported:
  150.  
  151.     (1) Ordinary initialization of option variables.
  152.  
  153.     (2) Change these options according to the data installed by
  154.         the CONFIG program.
  155.  
  156.     (3) Optionally, read options from an environment variable
  157.         or from an options file.
  158.  
  159.     (4) Get options from the command line; these can change
  160.         between filenames.
  161.  
  162. At any stage after stage 1, if any option data is not specified, the
  163. option values default to those set at an earlier stage.
  164.  
  165. Note that using CONFIG avoids using up scarce environment space, and
  166. eliminates the bother of setting up and locating an options file,
  167. although it may be preferred to also use an options file if there is
  168. a large amount of option data.  If an option file is necessary, CONFIG
  169. can define its pathname.
  170.  
  171. The Skel.pas program is a "skeleton" program that outlines the code
  172. needed to initialize a program and then control it from the command
  173. line.  The user (programmer) fills in application-dependant details.
  174.  
  175. The Skel.pas program uses the Params unit.  The Params unit defines
  176. a ScanPars procedure that scans the command line and interprets it.
  177. The ScanPars procedure calls a ParseOpts procedure to collect option
  178. data from parameters that begin with a '/', and calls a user-defined
  179. DoFile procedure for the other parameters.  The ParseOpts procedure
  180. calls a user-defined SetOpts procedure that interprets the options.
  181.  
  182. But before the command line is interpreted (stage 4), the program
  183. calls the ParseOpts procedure to scan the Config.cdata (stage 2),
  184. using the same interpretation as for the command line.  Here is the
  185. basic calling hierarchy:
  186.  
  187.                    program *
  188.                       |
  189.               2 .-----------. 4
  190.                 |           |
  191.                 |       ScanPars
  192.                 |           |
  193.                 | .-----------------.
  194.                 | |                 |
  195.               ParseOpts           DoFile *
  196.                 |
  197.                 |
  198.               SetOpt *
  199.  
  200. The '2' and '4' indicate stages 2 and 4.  The procedures marked '*'
  201. are user-defined.  The user program also includes a ShowUsage procedure
  202. to explain the options and also to report the default option values.
  203. The Params unit also provides procedures ShowDefault, RptError, and
  204. ChkFlg, and functions GetInt and GetBool to support the user-defined
  205. routines.
  206.  
  207. The Params unit initializes the variable ParNo to = -1, but when
  208. ParseOpts is called by ScanPars, ParNo is used to index the command-
  209. line parameters ("for ParNo:= 1 to ParamCount do ..").  Thus, for any
  210. options that are to be changable only in stage 2 (not stage 4), SetOpt
  211. can use the condition "if ParNo < 0".  If needed, ParNo = 0 can be used
  212. to indicate stage 3.
  213.